Amiga Plus 1997 #1/Amiga Plus CD - 1997 - No. 01.iso/pd/programmierung/installproged/sources/devmanual_eng

Text File | 1996-06-03 | 12KB | 454 lines

              -----------------------------------------------

                ProgED V2.1 by Giovanni Lambiase (C) 1995-96

                             Developers notes

              -----------------------------------------------


--------------------
 1. Main structures
--------------------

    If you want know something about structures see file PED.h.



------------
 2. Scanner
------------

    A scanner must be written using an ASM function or a C function.
If you use a C function you MUST use __asm, __saveds & register __XX
directives of SAC/C. Hovewer you MUST NOT use startup modules. The first
location must be the start location of your function. The search function
will receive two arguments in A0 & A1 registers:

    A0: Address of the line buffer. It points to a string 0-terminated.

    A1: Address of the name buffer.

    The function MUST return in D0 register the length of the string
written in the buffer pointed by A1. If your function fails in the
search you must return 0.

    NOTE: You MUST, hovewer, save all register in the stack at the entry
          of you function and load all them at the exit.



-----------
 3. Folder
-----------

    You may create a folder using same rules explained for scanners:

      1) Use a C Function or ASM function
      2) Use __asm,__saveds & register __XX directives
      3) Don't use startup modules
      4) First location must be the function start
      5) You must, hovewer, save all register in the stack at the entry
         of you function and load all them at the exit.

    A folder will receive arguments in the following registers:

    A0: Address of PEDWindow structure. You have to work on the text
        contained in this window.

    D0: Cursor column number (0=first column).

    D1: Cursor line number (0=first line). This value is ABSOLUTE. This
        means that it's the REAL line number from text start (generally
        line number are computed jumping over a fold!).

    A1: Address of a long-word. Using this address the function MUST
        write in the long-word the start line number of the fold, if
        found. To compute this value the function MUST get the
        ABSOLUTE line number (0=first line).

    A2: Address of a long-word. Using this address the function MUST
        write in the long-word the end line number of the fold, if
        found. To Compute this value the function MUST get the
        ABSOLUTE line number (0=first line).

    A3: Points to a buffer. If your function has found a fold it
        must write in this buffer the name of the fold. ProgED
        will show it. Generally you'll write here the name of
        the function found.

    The scanner function MUST return in D0 register 1 if it found a fold,
else 0. If a fold was found your function must return, also, the start
& end line numbers in the longwords pointed by A1 & A2 and the function
name in the buffer pointed by A3.

    NOTE: the 'FOLD ALL' function is executed calling your function
on ALL lines of the text. At each call the cursor will be at the
first column (D1 will contain 0).



----------------
 4. API Clients
----------------

    ProgED allow you to hook-up external applications (called "clients")
An API client is simply an executable (written in any language). This
executable must register itself at ProgED API port. Thus ProgED can
trace his clients and send them some info about what they'ld do.
The messages that a client can send to ProgED (in his API port called
"PED_API") have the following structure:

    struct APIMessage
    {
        struct Message     am_Message;
        ULONG              am_MsgType,
                           am_MsgArg[10],
                           am_RC;
    }

    am_Message:

         standard exec msg.

    am_MsgType:

         Type of msg.

    am_MsgArg[]:

         Array of arguments of the msg.

    am_RC:

         Return code.




    A client can send to ProgED the followings type of msgs:

    PED_API_REGISTER:

          "Register me.".In am_MsgArg[0] you must supply a pointer to an
          APIClient structure. This msg return nothing.

    PED_API_UNREGISTER:

          "Unregister me.".This msg have to be used if the client want to
          go away (!?!). It needs in am_MsgArg[0] the pointer you supplied
          for PED_API_REGISTER. This msg return nothing,too.

    PED_API_ADD_INTERNAL_COMMAND:

          A client can add a new internal command. To do so, you have to
          create an ArexxExtCmds structure and put its address in
          am_MsgArg[0]. This msg return nothing,too.


    PED_API_REM_INTERNAL_COMMAND:

          If you want to remove a previously added internal command, you
          have to use this msg. Put the address of your ArexxExtCmds
          structure in am_MsgArg[0]. This msg return nothing,too.

    PED_API_GET_ACTIVE_WINDOW:

          Get the address of PEDWindow structure currently active.
          You'll find this address in am_RC.

    PED_API_GET_WINDOW_LIST:

          Get the pointer to the first PEDWindow structure in the ProgED
          list. You'll find this address in am_RC.

    PED_GET_SCREEN_ADDRESS:

          Get the ProgED screen address. If ProgED is actually iconified
          return NULL. You'll find this address in am_RC.

    PED_GET_PREFS_ADDRESS:

          Get the address of the Prefs structure in am_RC.

    PED_GET_PUBSCRNAME:

          Get the ProgED public screen name in am_RC.

    NOTE: The ArexxExtCmds structure MUST remain valid until you have
          replied to the PED_API_REM_INTERNAL_COMMAND. After this you
          can free or reuse it.




    ProgED can send to a client the following msgs:

    PED_API_SHOW:

          "I opened my screen. My screen address is in am_MsgArg[0].The
          public screen name is in am_MsgArg[1].". Using this info you
          can open your windows on the ProgED screen. You'll receive
          this msg ONLY if you specified NOTIFY_ON_SHOWHIDE in the
          flags field of the APIClients structure (see it).

    PED_API_HIDE:

          "I'm closing my screen!". You'll receive this msg when ProgED
          is about to closing its screen. Close ALL your windows. You'll
          receive this msg ONLY if you specified NOTIFY_ON_SHOWHIDE in
          the flags field on the APIClients structure (see it).

    PED_API_KEY:

          "User pressed a key!". The client can get the relative IntuiMessage
          structure using am_MsgArg[0]. This field will contain the address
          to an IntuiMessage structure specifing a RAWKEY msg. In am_MsgArg[1],
          furthermore, client can get a pointer to a struct PEDWindow which
          received the RAWKEY message.
          You'll receive this msg ONLY if you specified NOTIFY_ON_KEY in
          the flags field on the APIClients structure (see it).

          NOTE: Hovewer, when you reply this msg, ProgED will execute
                the action due to the key. You can't modify the IntuiMessage,
                too. That is an Intuition message! (:-o

    PED_API_QUIT:

          "I'm quitting!". If your client receive this msg you MUST close
          all your window AND QUIT. You MUST NOT use the API port
          after receving this message! Your client shouldn't try to
          remove commands & registeration! YOU MUST ONLY QUIT!




    Here you can find some info about APIClient structure.


    struct APIClient
    {
        struct MsgPort          *ac_ClientPort;
        ULONG                    ac_Notify;
        char                    *ac_name;
        struct APIClient        *ac_Next;
    }

    ac_ClientPort:

        Address of the client message port. You must supply here a
        message port. ProgED will send its message to you using this
        port.

    ac_Notify:

        If you specify NOTIFY_ON_SHOW_HIDE you will get PED_API_SHOW &
        PED_API_HIDE messages. Using NOTIFY_ON_KEY flag you can get
        some info about key pressed with PED_API_KEY msgs.

    ac_Name:

        Client name.

    ac_Next:

        Set up to NULL. It will be filled later using the address of
        next client.




    struct ArexxExtCmds
    {
        UBYTE                    External;
        char                    *Name;
        char                    *Template;
        void                    *Defaults[MAXREXXARGS];
        LONG ASM                (*CommFunc)( RG(a0) struct CommandData *);
        struct ArexxExtCmds     *NextCmd;
    }

    External:

        Set up to TRUE. It means this is an "external" command.

    Name:

        Command name. Write it using case letters.

    Template:

        ReadArgs template.

    Default[]:

        Array of default values for the arguments.

    CommFunc:

        Address of the function of the command. This function must be
        written in ASM or using __asm & __saveds directives. It will
        receive a structure CommandData in A0 register. This function
        must return in D0 register an error code (see RC_xxx defines).

    NextCmd:

        Set up to NULL.




    struct CommandData
    {
        char              *CommandLine;
        void             **CommandArgs;
        struct MyWindow   *CurrentWindow,
                          *FirstWindow;
        struct Prefs      *CurrentPrefs;
        LONG ASM (*ExecuteInternalCommand)(RG(a0) char *);
    }

    CommandLine:

        This field points to a string containing the entire command
        line. Use it as you like.

    CommandArgs:

        Points to an array of void *. This array is the output of
        the ReadArgs function on the CommandLine String. See ReadArgs
        on how to use these pointers.

    CurrentWindow:

        Points to the PEDWindow actually active.

    FirstWindow:

        Points to the first PEDWindow.

    CurrentPrefs:

        Points to a Prefs structure containing actual preferences.

    ExecuteInternalCommand:

    It's a pointer to an assembler function. You can call this
        function to execute a ProgED internal command. To do so,
        Put in A0 register a pointer to a string containing the
        command string you wish to execute. In D0 register you
        will get a return code (RC_xxx).

        NOTE: Don't use the ProgED ARexx port to execute an
        internal command! Doing that you'll hang up ProgED and
        the client!



----------------------
 5. Utility functions
----------------------

    The following C functions are useful if you want to write your own
folder or scanner. You can use it in your function cutting out them.
This functions search for lines in ProgED texts.



/*****
 *
 * FUNCTION:    struct Line *SearchLine(struct Line *line,int y)
 *
 * AIM:        Search for the y-th line (not jumping over folds) starting
 *        from the first line of the text supplied by "line".
 *
 * RESULT:    A pointer to the searched line.
 *
 ****/

struct Line *SearchLine(struct Line *line,int y)
{
    while(((y--)>0)&&(line))    line=NextLine(line);
    return(line);
}



/*****
 *
 * FUNCTION:    int SearchLine2(struct Line *line,int y)
 *
 * AIM:        Search for the line number (jumping over folds) of the
 *        line numbered "y" (not jumping over folds).
 *
 * RESULT:     # of the searched line.
 *
 ****/

int SearchLine2(struct Line *line,int y)
{
    int    n=0;

    while(((y--)>0)&&(line))
    {
        if (!line->Folder)    n++;
        else    if (line->NextLine)
                if (!line->NextLine->Folder)    n++;
        line=line->NextLine;
    }
    if (line)    return(n);
    else        return(0);
}



/*****
 *
 * FUNCTION:    int SearchLine3(struct Line *first,struct Line *line)
 *
 * AIM:        Search for the line # (not jumping over folds) of the
 *        line pointed by "line"."first" points to the first
 *        line of the text.
 *
 * RESULT:    # of the searched line.
 *
 ****/

int SearchLine3(struct Line *first,struct Line *line)
{
    long    n=0;

    while(first)
    {
        if (first==line)    break;
        n++;
        first=first->NextLine;
    }
    return(n);
}



/*****
 *
 * FUNCTION:    struct Line *SearchLine4(struct Line *line,int y)
 *
 * AIM:        Search for the address of the line numbered y-th.
 *        "line" points to the first line of the text.
 *        The result of this function is ABSOLUTE
 *        (it doesn't jump over folds).
 *
 * RESULT:    A pointer to the searched line.
 *
 ****/

struct Line *SearchLine4(struct Line *line,int y)
{
    while(((y--)>0)&&(line))    line=line->NextLine;
    return(line);
}